Support flashing in Secure Download Mode by enody-carter · Pull Request #990 · esp-rs/espflash

enody-carter · 2026-01-01T23:54:12Z

Fixes 726

When secure download mode is enabled, the flashing happens via the ROM UART download which does not support all commands. Utilize standard FlashBegin, FlashData, and FlashEnd when the stub is not utilized for flashing. Additionally, do not attempt to disable the watchdog or verify the flash when in secure download mode.

This implementation was based esptool's implementation. I included the write protection for base address < 0x8000 to protect the boot loader. In esptool this is allowed via a --force flag, but no such flag is present in espflash, so I defer to you on what you would like to do regarding this protection.

espflash/src/flasher/mod.rs

Copilot

Pull request overview

This PR adds support for flashing ESP32 devices in Secure Download Mode, which uses ROM UART download with restricted command availability. The implementation avoids using compression (which requires stub loader commands not available in Secure Download Mode) and instead uses standard FlashBegin/FlashData/FlashEnd commands. Additionally, the PR implements bootloader protection to prevent writes below address 0x8000 and disables watchdog disable, verify, and skip operations which rely on restricted commands.

Key Changes:

Implements non-compressed flash operations using FlashBegin/FlashData/FlashEnd for Secure Download Mode
Adds bootloader protection to reject writes below 0x8000 when Secure Download Mode is enabled
Skips watchdog disable, verify, and skip operations in Secure Download Mode

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
espflash/src/target/flash_target/esp32.rs	Implements dual-path flashing logic (compressed with stub vs uncompressed without stub), updates watchdog disable to skip in Secure Download Mode, renames need_deflate_end to need_flash_end
espflash/src/flasher/mod.rs	Adds bootloader protection checks and warning messages for Secure Download Mode in both image and binary flashing methods
espflash/src/error.rs	Adds new error variant for bootloader protection violation
CHANGELOG.md	Documents the new Secure Download Mode support feature

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-05T15:53:24Z

espflash/src/flasher/mod.rs

+            for segment in image_format.clone().flash_segments() {
+                if segment.addr < BOOTLOADER_PROTECTION_ADDR {
+                    return Err(Error::SecureDownloadBootloaderProtection);
+                }
+            }


The image_format is cloned here to iterate segments for address validation, then the original is consumed later at line 964. This could be optimized by collecting segments once into a Vec, validating addresses, then flashing from the Vec. However, this would require changing how flash_segments works since it consumes self.

Consider refactoring to collect segments once and reuse them, or provide a non-consuming iterator method for flash_segments to avoid the clone.

I think this is valid, but also begs the question whether we should split the check out into its own fn, as its duplicated in more than one place.

I agree, I ended up not breaking it out initially as load_image_to_flash() and write_bins_to_flash() are close to duplicates right now. I'm happy break this out into a new fn and open a new PR to track a unification of these and introduce a --force flag if desired).

Maybe we can do the deduplication in this PR and leave the --force flag for an upcoming PR?

Copilot · 2026-01-05T15:53:24Z

espflash/src/target/flash_target/esp32.rs

+            let mut data = segment.data.to_vec();
+            let padding = (flash_write_size - (data.len() % flash_write_size)) % flash_write_size;
+            data.extend(repeat_n(0xff, padding));
+            data


When compression is disabled, the data is manually padded here with 0xff bytes to align to flash_write_size. However, at line 229, the FlashData command is also configured with pad_to: flash_write_size, which causes the data_command function to apply padding again. This results in double padding.

The manual padding should be removed since the FlashData command handles padding automatically via the pad_to parameter.

Copilot · 2026-01-05T15:53:25Z

espflash/src/target/flash_target/esp32.rs

When FlashBegin is called (non-compression path), need_flash_end should be set to true to ensure FlashEnd is called in the finish() method. Without this, the flash operation won't be properly completed in Secure Download Mode.

Add self.need_flash_end = true; after the FlashBegin command, similar to what's done for the compression path at line 183.

Suggested change

)?;

)?;

self.need_flash_end = true;

This is absolutely valid, messed up my rebase and caused this.

espflash/src/target/flash_target/esp32.rs

espflash/src/error.rs

espflash/src/target/flash_target/esp32.rs

MabezDev

Sorry, I meant to come back and see copilots output but I got distracted. I've resolved and added some comments on relevant review items.

MabezDev · 2026-01-07T14:05:33Z

espflash/src/flasher/mod.rs

+            for segment in image_format.clone().flash_segments() {
+                if segment.addr < BOOTLOADER_PROTECTION_ADDR {
+                    return Err(Error::SecureDownloadBootloaderProtection);
+                }
+            }


I think this is valid, but also begs the question whether we should split the check out into its own fn, as its duplicated in more than one place.

MabezDev · 2026-01-28T13:50:37Z

Hey @enody-carter this is a great addition, and really close to complete! Any chance you can come back and push it over the finish line?

enody-carter · 2026-01-28T13:53:54Z

Yes! Had a bunch of travel, but will wrap up today.

enody-carter · 2026-01-28T17:17:07Z

I believe I have addressed all feedback. Additionally, I tested with the following procedure:

On a secure boot enabled ESP32-C6:

write-bin an encrypted and signed application to 0x20000, ensure successfully written and device boot app (verified via UART logging)
attempt to write-bin an encrypted and signed application to 0x0000, ensure write was not attempted

On a non-secure boot enabled device:

attempt a write-bin to 0x0000, ensure write succeeds via flash verification.

The tests were performed on macOS 15 and Ubuntu 24.04.

SergioGasquez

LGTM! Thanks for the contribution, sadly we have no way of currently testing it on HIL, maybe this is something we could improve in the future. This would probably need a rebase once #996 is merged as the required jobs are now updated!

* With secure download enabled, the stub is not utilized so compressed flashing is unavailble. In this situation, use the uncompressed flashing commands. * If secure download is enabled, prevent flashing data to addresses below 0x8000 to prevent overwriting the bootloader and bricking the device

SergioGasquez · 2026-02-05T11:14:16Z

Hi @enody-carter!

I included the write protection for base address < 0x8000 to protect the boot loader. In esptool this is allowed via a --force flag, but no such flag is present in espflash, so I defer to you on what you would like to do regarding this protection.

Mind sharing where you found this information? Afaik, in esptool, the bootloader write protection is placed when secure boot or flash encryption are enabled (see https://docs.espressif.com/projects/esptool/en/latest/esp32h2/esptool/basic-commands.html#flash-protection)

Doing esptool --port /dev/ttyUSB0 --no-stub --chip esp32h2 write_flash -fs 4MB 0 app.bin without requiring --force

enody-carter · 2026-02-05T12:44:21Z

Hello Sergio,

There are a series of checks in esptool cmds.py (starting at line 548).

They perform a series of more specific tests (chip specialized, is encryption also enabled on Secure Boot V2), which are all gated behind the --force flag. There is a comment regarding the safety of writing the boot loader:

Check if Secure Boot V1 is active (ESP32 only)

V1 stores the signing key in chip eFuse - bootloader reflash is dangerous

V2 uses external signing key - bootloader updates are safe

but during the development / testing of this, I ended up (I think) bricking a couple devices that are using the ESP32-C6 WROOM1 (secure boot & encryption enabled) directly and do not have the BOOT pin tied to a button. This resulted in an invalid boot loader that caused a boot loop, with me unable to put a working bootloader back on.

I do not believe any sort of write protection is put in place when secure boot v2 is enabled. In the linked document, only erase is disabled, but I believe you could accomplish the same amount of bricked device via writing an invalid 2nd stage bootloader to flash. There are the various modes of secure download that tend to be enabled at the same time, but from my testing no direct write protection is enabled on the device itself.

That being said, I do think there is room for a more granular set of checks regarding the use of secure download mode, secure boot, and flash encryption. I will need to acquire more hardware for testing before I can feel confident implementing these though !

SergioGasquez · 2026-02-05T14:12:40Z

There are a series of checks in esptool cmds.py (starting at line 548).

But the bootloader protection is only applied when using secure boot (which is not yet implemented in espflash), not sure if theres any reason to keep in espflash at the momment as it prevents using the flash subcommand (the equivalent of esptool --chip esp32c3 -p /dev/ttyUSB0 --no-stub --flash-size 2MB 0x0 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello_world.bin , which works in an sdm chip)

enody-carter · 2026-02-05T14:21:30Z

Ah, I see. This inadvertently coupled SDM and Secure Boot. I apologize, I definitely let the details of my boot process leak into this patch.

I am working on broader support for secure boot in espflash, at which point this would be the right change. Want me to open a PR to remove the 0x8000 check until secure boot is supported?

SergioGasquez · 2026-02-05T14:41:20Z

I am working on broader support for secure boot in espflash, at which point this would be the right change. Want me to open a PR to remove the 0x8000 check until secure boot is supported?

Thanks, looking forward to the secure boot support <3 ! Dont worry, I can remove the 0x8000 check in #1002

enody-carter force-pushed the secure_download_mode branch 4 times, most recently from e67bec9 to 5398109 Compare January 2, 2026 00:06

MabezDev reviewed Jan 5, 2026

View reviewed changes

espflash/src/flasher/mod.rs Outdated Show resolved Hide resolved

espflash/src/flasher/mod.rs Outdated Show resolved Hide resolved

enody-carter force-pushed the secure_download_mode branch 2 times, most recently from 5d4f443 to 067f040 Compare January 5, 2026 14:47

MabezDev requested a review from Copilot January 5, 2026 15:48

Copilot started reviewing on behalf of MabezDev January 5, 2026 15:48 View session

Copilot AI reviewed Jan 5, 2026

View reviewed changes

MabezDev reviewed Jan 7, 2026

View reviewed changes

MabezDev added the status:awaiting-response Awaiting a response from the author label Jan 13, 2026

enody-carter force-pushed the secure_download_mode branch from 067f040 to 40efde2 Compare January 28, 2026 17:04

SergioGasquez approved these changes Jan 29, 2026

View reviewed changes

enody-carter force-pushed the secure_download_mode branch from 40efde2 to 2571df6 Compare January 30, 2026 12:14

SergioGasquez added this pull request to the merge queue Jan 30, 2026

github-merge-queue bot removed this pull request from the merge queue due to failed status checks Jan 30, 2026

SergioGasquez added this pull request to the merge queue Jan 30, 2026

github-merge-queue bot removed this pull request from the merge queue due to failed status checks Jan 30, 2026

SergioGasquez added this pull request to the merge queue Jan 30, 2026

github-merge-queue bot removed this pull request from the merge queue due to failed status checks Jan 30, 2026

MabezDev added this pull request to the merge queue Feb 1, 2026

github-merge-queue bot removed this pull request from the merge queue due to failed status checks Feb 1, 2026

SergioGasquez added this pull request to the merge queue Feb 2, 2026

github-merge-queue bot removed this pull request from the merge queue due to failed status checks Feb 2, 2026

MabezDev added this pull request to the merge queue Feb 2, 2026

github-merge-queue bot removed this pull request from the merge queue due to failed status checks Feb 2, 2026

SergioGasquez added this pull request to the merge queue Feb 2, 2026

Merged via the queue into esp-rs:main with commit 4b0cb41 Feb 2, 2026
74 of 77 checks passed

SergioGasquez mentioned this pull request Feb 6, 2026

Add SDM HIL #1002

Merged

                                   })?;
                                   Ok(())
                               },
                           )?;

Comments

Conversation

enody-carter commented Jan 1, 2026

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

MabezDev Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

enody-carter Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

SergioGasquez Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

enody-carter Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MabezDev left a comment

Choose a reason for hiding this comment

Uh oh!

MabezDev Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

MabezDev commented Jan 28, 2026

Uh oh!

enody-carter commented Jan 28, 2026

Uh oh!

enody-carter commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SergioGasquez left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SergioGasquez commented Feb 5, 2026

Uh oh!

enody-carter commented Feb 5, 2026

Check if Secure Boot V1 is active (ESP32 only)

V1 stores the signing key in chip eFuse - bootloader reflash is dangerous

V2 uses external signing key - bootloader updates are safe

Uh oh!

SergioGasquez commented Feb 5, 2026

Uh oh!

enody-carter commented Feb 5, 2026

Uh oh!

SergioGasquez commented Feb 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

enody-carter commented Jan 28, 2026 •

edited

Loading